fix: type merged fields as child-wins, matching the runtime - #54

Retires the last recorded type lie in extend: merged fields were typed S & S2 while the runtime is { ...parent.fields, ...nextFields } — child wins per key. A variant redeclaring an inherited field under a different brand read as both brands while holding one. The identical lie was fixed for the computed map in the previous release (MergedComputed); this is its sibling, built to the same playbook.

The change

export type MergedFields<S extends Fields, S2 extends Fields> = Omit<S, keyof S2> & S2;

All five S & S2 positions in AbstractEntity["extend"] convert. The return type and the two InputOf positions carried the real lie — a rule's or derivation's d typed a redeclared field as both brands. The two keyof bounds were provably equivalent key sets (measured, including the symbol-key case), changed for single-spelling consistency; they are the safe revert if const-inference ever misbehaves.

The old "left as S & S2, known, why" comment is retired — its question now has a measured answer.

The emit playbook, followed first pass

The MergedComputed episode taught that the inline form emits a dangling type parameter into consumers' declarations under TS 5.9.3 (TS2304). MergedFields is a named export from the start, registered on all seven surfaces: the alias, index.ts's emit-nameability list, the *Src + namespace member, emit-guards.ts (with Record<never, never> as the argument shape that broke last time), typedoc.json, and types.md's four sub-surfaces. Review confirmed all seven and searched for an eighth — there is none.

Measured cost: the emitter writes the alias by reference; the consumer's index.d.ts grew 10,061 → 10,145 bytes — +42 per variant. The deferral reason ("TS7056 budget on every entity") is answered, not assumed: no TS7056, no TS2304, no TS4023 on either compiler.

What the honest surfaces are — same story as computed

A variant's instance type still shows the intersection for a redeclared key, because BehaviourOf<This> carries the root's instance unmapped (mapping it breaks abstract members, TS2425 — pinned). Entity.Output, toJSON() and output.shape are the honest surfaces, exactly as documented for redefined computed keys. declaration.md's caveat is generalised to redeclared keys in either map, and the option table gains a fields row ("merged per key"), kept clearly distinct from the concatenating lists.

Guards, all proven discriminating

• Type: Entity.Output<typeof Variant>[key] is the variant's brand alone. The @ts-expect-error is proven load-bearing the honest way: restoring S & S2 yields exactly one diagnostic — TS2578 on the directive — and the comments say precisely that (an intersection assigns to each constituent, so the failure surfaces as the directive going unused, not as the positive line breaking). A pre-existing comment on the computed twin made the stronger, false claim; fixed here too.
• Runtime: root Code5 (length(5)) vs child Digits (/^\d+$/) discriminates all three merge semantics — "abcde" rules out parent-wins, "42" rules out an intersect merge, "12345" proves the key is not dropped. Hand-verified in review.

Breaking

minor. No entity declaration that compiled stops compiling. Code consuming a redeclared key through the old intersection type may now fail to compile instead of passing silently — which is the honest type doing its job. The changeset says so, split exactly that way. Also folds in: CLAUDE.md's declaration-emit-names count corrected to nine (it understated by two even before this branch).

Test plan

• 172 package tests (one new), test:types with every directive used, full six-step gate including the four-step consumer pass on 7.0.2 and 5.9.3 — green, uncached
• Review measured the keyof-equivalence and brand-assignability claims independently rather than trusting the report

Known follow-up, deliberately not here: no direct pin on a redeclared field that is also immutable/generated on the root.

🤖 Generated with Claude Code